PsL Monthly 1993 December/PSL Monthly Shareware CD-ROM (December 1993).iso/prgmming/dos/c/wstr.exe/WSTR.DOC

Text File | 1993-02-12 | 44KB | 1,089 lines

Wheaton Strings library documentation

October 10, 1989
February 20, 1991 (minor update)
May 15, 1992 (minor update)
October 20, 1992 (minor update)
January 27, 1993 (add String40 and String120 - fix some documentation bugs)

Copyright (c) 1992, 1993 by Paul Wheaton

Note that this documentation does not cover all of the features of the
provided in this library.  For that, you will have to look at the header files.

The Wheaton Libraries are shareware. Anyone may use the libraries provided
that they do not change them.  If you want to change them or if you want
phone support from me, you must pay $50. This in the hope that the hundreds
of vendors that are creating their own string libraries can go with just
one - I'm pretty tired of getting a library in that seems like it will be
pretty cool, just to find out that it uses the same identifiers as
something else and there are then link conflicts.

For those programmers that never read documentation but have
mysteriously made it this far, just look quickly at section 1.1.4 and
5.1.  To make these libraries available, you need to include
<Strings.h> link with WLIB.LIB and FATAL.OBJ (or WW.LIB which includes
a different FATAL.OBJ).

This Strings library, consisting of one class and a few independent
functions, provides an easier, more intuitive way to manipulate
strings.  By including this stuff into your programs you can use (or
create!) functions that do not need chunks of memory pre-allocated for
them.  Concatenation is done with "+" or "+=" instead of "strcat".
Comparison is done with "==", "!=", "<", etc. instead of "strcmp".
Source ends up being more readable, and less verbose.  Many common
string manipulation errors are completely eliminated.  For programmers
new to "C", these libraries provide more functionality with fewer
operators to memorize, thus reducing the dreaded learning curve.

(note - there is now more than one class, but you may treat the class
"String" as if it were just one.  Later, when you have more experience, you
can use the classes String40 and String120 for optimization)

Strings are automatically converted from type String to char* and back
as needed.  The two types can often be mixed to give the same results.


      Strings
1       Advantages over C
1.1       for programmers new to C
1.1.1       less to memorize
1.1.2       more intuitive
1.1.3       similar to other languages
1.1.4       faster to learn
1.2       for old C programmers
1.2.1       less to type
1.2.2       less worry about low level stuff: concentrate more on program
1.2.3       more readable
1.2.4       eliminate overflow errors
1.2.5       faster executable
              length does not need to be calculated
1.2.6       use less memory
              don't need to allocate memory to cover "worst case"
1.2.7       functions that are more independent (don't need storage space)
2       Disadvantages from C
2.1       speed overhead
            allocating memory in the heap at creation and appending
2.2       storage overhead
            storing length and extra pointers
3       A little bit about how this works
4       Implementing this with char* for optimal performance
5       Functions
5.1       String class member functions
5.1.1       declaring a String
5.1.1.1       based on a given string constant or char*
5.1.1.2       based on a character
5.1.1.3       based on another String
5.1.1.4       without initialization
5.1.1.5       extra allocation
5.1.2       Length() or Size()
5.1.3       + (concatenation)
5.1.4       += (appending form of concatenation)
5.1.5       = (assignment) and conversions
5.1.6       ==,!=,<,>,<=,>= (comparison)
5.1.7       () or At() (retrieving substrings)
5.1.7.1       Before(), Through(), From() and After()
5.1.8       [] (String char reference)
5.1.9       Left(), Right(), Center(), Just()  (justification)
5.1.10      Capacity() (report current allocation)
5.1.11      ReAlloc() (change capacity)
5.1.12      ToLower() (force all upper case letters to lower case)
5.1.13      ToUpper() (force all lower case letters to upper case)
5.1.14      Index() (find the index of a char)
5.1.15      Insert() (insert a char or a sting into the string)
5.1.16      Delete() (delete characters from the string)
5.2       non-member functions
5.2.1       Str() (convert integers to String)
5.2.2       Form() (convert reals to a String using a format)
5.2.3       StringOf() (return a string of chars)
5.2.4       Spaces() (return a String of a certain number of spaces)
5.2.5       LeftText(), RightText(), CenterText(), JustText()



1 Advantages over C

  I hope to show that using these String libraries in C++ is a great deal
  easier than using the ANSI C string libraries or any string library that
  could possibly be written in C.  It is my opinion that productivity in
  string manipulation development will increase by a factor of four for
  those application programmers that use this library.

1.1 for programmers new to C

  Any time that you move to a new language there will be a learning curve.
  C is notorious for being too terse and, thus, hard to read and tougher to
  learn.  Much of this has to do with being a "mid level language":  Easier
  to work with than assembly yet harder than "high level languages" such as
  Pascal or FORTRAN.  C gains you a great deal of portability and runtime
  effeciency over most "high level languages".  C++ with a healthy set of
  libraries provides all of the advantages of C coupled with the advantages
  of a high level language.  This library should make string manipulation
  easier than not only C, but FORTRAN, Pascal, BASIC, LISP or Modula-2.  A
  programmer new to this library will probably find all of the string
  manipulation features that they appreciated most in their favorite
  languages and then some new twists that will make their programming lives
  even easier.

1.1.1 less to memorize

  C++ cures some of the idiosyncrasies of C that directly effect
  string manipulation libraries, one of the worst being the pointer to
  a character concept.  In order for a programmer to keep from getting
  into trouble when manipulating strings in C, they must memorize how
  the compiler handles them (the strings):  C Strings are an array of
  characters terminated by a null character; strings are referenced by
  a pointer to the first element of the string; runtime range checking
  is not standard and is performed with library routines when the size
  of the string is passed.

  In this library, how the String is actually stored and manipulated
  is hidden from the applications programmer.  Runtime range checking
  is performed by the library so the applications programmer can
  concentrate on their application rather than monitor the size of
  their strings and make sure everything will fit.  Since string
  manipulation using this library is similar to working with numbers
  in C or C++, all of the exceptions for plain C string handling never
  have to be learned.

1.1.2 more intuitive

  ANSI C maintains a great deal of exceptions when it comes to string
  handling.  For example, if you have two strings, S1 and S2,
  assignment of one from the other does not result in two identical
  copies of the string, it results in two pointers pointing to the
  same string:  Modifying one effects the other.  Generally, when an
  assignment is made such as X=Y, the contents of X are separate from
  Y yet the same.  This library supports the more intuitive assignment
  operation as well as other operators and functions that any string
  library *ought* to have.

1.1.3 similar to other languages

  Of course, all of the functions and operators available in C are
  also available in C++.  Many of them (C functions) will work with
  the String type as well as good ole char*.

  In Turbo Pascal

    Var S1,S2:String;
    Begin
      S1:="oatmeal";
      S2:="I like "+S1+".";
    End;

  In BASIC

    550 S1$="oatmeal"
    560 S2$="I like "+S1$+"."

  In FORTRAN

    char S1*8
    char S